W06-2. Kubernetes 입문 - 실습 가이드
6주차 실습: 내 노트북에 Kubernetes 클러스터 만들고 Pod 띄우기
- Docker Desktop 으로 노드 3개짜리 Kubernetes 클러스터를 만든다.
kubectl로 클러스터와 시스템 구성 요소를 들여다본다.- 4주차에 Docker Hub 에 올린 방명록을 Pod 로 띄우고 브라우저로 접속한다.
- 일부러 고장 낸 Pod(ImagePullBackOff, CrashLoopBackOff)를 진단한다.
| 실습 | 내용 | 시간 |
|---|---|---|
| 0 | 클러스터 만들기 | 8분 |
| 1 | 클러스터 둘러보기 | 7분 |
| 2 | 첫 Pod (명령형) | 5분 |
| 3 | 방명록 Pod (YAML, 선언형) | 10분 |
| 4 | Pod 를 지우면? | 2분 |
| 5 | 고장 난 Pod 진단하기 | 8분 |
| 6 | Namespace | 3분 |
| 7 | 정리 | 2분 |
실습 0. 클러스터 만들기
0-1. Docker Desktop 에서 만들기
- Docker Desktop 대시보드 왼쪽 메뉴에서 Kubernetes 를 누릅니다.
- Create cluster 를 누릅니다.
- 클러스터 종류에서 kind 를 고릅니다.
- Nodes(노드 수): 3 (메모리가 8GB 인 노트북이면 2)
- Version: 기본값 그대로
- Create 를 누르고 1~2분 기다립니다. 처음에는 노드 이미지를 받느라 더 걸릴 수 있습니다.
- 대시보드 아래쪽(또는 Kubernetes 화면)에 Kubernetes running 이 보이면 완료입니다.
| kubeadm | kind | |
|---|---|---|
| 노드 수 | 1개만 | 여러 개 |
| 버전 선택 | 불가 | 가능 |
| 만드는 시간 | 약 1분 | 약 30초 |
서버 여러 대에 Pod 가 나뉘는 모습을 보려면 노드가 여러 개여야 합니다.
0-2. kubectl 이 이 클러스터를 보고 있는지 확인
kubectl config current-context
출력: docker-desktop
회사 업무 등으로 다른 클러스터를 쓰던 분은 kubectl 이 그 클러스터를 보고 있을 수 있습니다. 실습 클러스터로 바꿉니다.
kubectl config use-context docker-desktop
실습이 끝나면 원래 쓰던 컨텍스트로 되돌리세요(kubectl config get-contexts 로 목록 확인).
kubectl version
출력 예시:
Client Version: v1.36.1
Kustomize Version: v5.7.1
Server Version: v1.36.1
version difference between client (1.34) and server (1.36) exceeds the supported minor version skew 경고가 나온다면예전에 따로 설치한 오래된 kubectl 이 먼저 실행되고 있는 것입니다(실제로 겪음).
- 확인: macOS
which -a kubectl/ WindowsGet-Command kubectl -All - Docker Desktop 의 kubectl 위치: macOS
/usr/local/bin/kubectl, Windows%LOCALAPPDATA%\Programs\DockerDesktop\resources\bin\kubectl.exe(또는C:\Program Files\Docker\Docker\resources\bin\kubectl.exe) - 오래된 것을 지우거나 PATH 순서를 바꾸세요. 잘 모르겠으면 문의해 주세요.
실습 1. 클러스터 둘러보기
1-1. 노드 목록
kubectl get nodes
출력 예시 (노드 3개):
NAME STATUS ROLES AGE VERSION
desktop-control-plane Ready control-plane 78s v1.36.1
desktop-worker Ready <none> 67s v1.36.1
desktop-worker2 Ready <none> 67s v1.36.1
| 노드 | 역할 |
|---|---|
desktop-control-plane |
Control Plane (관리 본부: apiserver, etcd, scheduler, controller-manager) |
desktop-worker, desktop-worker2 |
Worker Node (방명록 같은 앱 Pod 가 실행되는 곳) |
자세히 봅니다.
kubectl get nodes -o wide
출력 예시: 가로로 길어서 오른쪽으로 스크롤해서 보세요.
NAME STATUS ROLES AGE VERSION INTERNAL-IP EXTERNAL-IP OS-IMAGE KERNEL-VERSION CONTAINER-RUNTIME
desktop-control-plane Ready control-plane 79s v1.36.1 172.23.0.3 <none> Debian GNU/Linux 13 (trixie) 6.6.87.2-microsoft-standard-WSL2 (amd64) containerd://2.3.1
desktop-worker Ready <none> 68s v1.36.1 172.23.0.2 <none> Debian GNU/Linux 13 (trixie) 6.6.87.2-microsoft-standard-WSL2 (amd64) containerd://2.3.1
desktop-worker2 Ready <none> 68s v1.36.1 172.23.0.4 <none> Debian GNU/Linux 13 (trixie) 6.6.87.2-microsoft-standard-WSL2 (amd64) containerd://2.3.1
- OS-IMAGE: 노드 안의 OS 입니다. 노트북이 macOS / Windows 여도 노드는 리눅스입니다(1주차의 리눅스 VM 안에서 돌기 때문).
- CONTAINER-RUNTIME:
containerd입니다. 1주차에 본 그 containerd 입니다.
1-2. 노드의 정체: 컨테이너
kind 방식에서는 노드 하나하나가 컨테이너입니다. Docker Desktop 대시보드 Kubernetes 화면에서 노드 목록을 보거나, 설정의 Show system containers (advanced) 를 켜면 docker ps 에도 노드 컨테이너가 보입니다.
"서버 3대" 처럼 보이지만 실제로는 노트북 안의 컨테이너 3개입니다. 원리를 배우기에는 충분하고, 실제 서버 클러스터와 명령은 똑같습니다.
1-3. 관리 본부의 구성 요소들
kubectl get pods -n kube-system
출력 예시:
NAME READY STATUS RESTARTS AGE
coredns-589f44dc88-jv6r9 1/1 Running 0 69s
coredns-589f44dc88-pxbhk 1/1 Running 0 69s
etcd-desktop-control-plane 1/1 Running 0 78s
kindnet-kg5rv 1/1 Running 0 68s
kindnet-kk4jr 1/1 Running 0 70s
kindnet-n7d4w 1/1 Running 0 68s
kube-apiserver-desktop-control-plane 1/1 Running 0 76s
kube-controller-manager-desktop-control-plane 1/1 Running 0 76s
kube-proxy-gpv8r 1/1 Running 0 68s
kube-proxy-hdbpr 1/1 Running 0 70s
kube-proxy-jvtsc 1/1 Running 0 68s
kube-scheduler-desktop-control-plane 1/1 Running 0 78s
| 이름에 들어간 것 | 강의 노트의 구성 요소 |
|---|---|
kube-apiserver-... |
창구 (apiserver) |
etcd-... |
장부 (etcd) |
kube-scheduler-... |
배차 (scheduler) |
kube-controller-manager-... |
감독 (controller-manager) |
kube-proxy-... |
교통 정리 (노드마다 1개씩) |
coredns-... |
클러스터 안의 DNS (8주차 Service 이름 찾기) |
kindnet-... |
Pod 끼리 통신하게 해 주는 네트워크 플러그인(CNI) |
Kubernetes 의 구성 요소 자체도 Pod 로 돌고 있습니다.
1-4. Namespace 목록
kubectl get namespaces
출력 예시:
NAME STATUS AGE
default Active 5m
kube-node-lease Active 5m
kube-public Active 5m
kube-system Active 5m
local-path-storage Active 5m
local-path-storage는 9주차에 쓸 저장소(볼륨) 자동 생성기가 있는 곳입니다.
실습 2. 첫 Pod (명령형)
docker run 처럼 명령 한 줄로 Pod 를 만들어 봅니다.
kubectl run study-nginx --image=nginx:1.30-alpine
kubectl get pods
출력 예시: 처음에는 ContainerCreating, 몇 초 뒤 Running 이 됩니다.
NAME READY STATUS RESTARTS AGE
study-nginx 1/1 Running 0 7s
상태가 바뀌는 것을 계속 보려면
kubectl get pods -w(Ctrl + C로 빠져나옴)
어느 노드에 배치됐는지 봅니다.
kubectl get pods -o wide
출력 예시:
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES
study-nginx 1/1 Running 0 8s 10.244.2.4 desktop-worker <none> <none>
scheduler 가 Worker Node 중 하나를 골라 배치했습니다. 사람마다 다른 노드가 나올 수 있습니다.
2-1. 무슨 일이 있었는지: describe 의 Events
kubectl describe pod study-nginx
출력 예시 (맨 아래 Events 부분):
Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Scheduled 8s default-scheduler Successfully assigned default/study-nginx to desktop-worker
Normal Pulled 8s kubelet spec.containers{study-nginx}: Container image "nginx:1.30-alpine" already present on machine and can be accessed by the pod
Normal Created 8s kubelet spec.containers{study-nginx}: Container created
Normal Started 8s kubelet spec.containers{study-nginx}: Container started
Scheduled(scheduler 가 노드 배정) → Pulling / Pulled(kubelet 이 이미지 받음) → Created / Started(containerd 가 컨테이너 실행)
2-2. 로그와 삭제
kubectl logs study-nginx
kubectl delete pod study-nginx
실습 3. 방명록 Pod (YAML, 선언형)
3-1. 작업 폴더와 YAML 파일
macOS:
mkdir -p ~/docker-study/k8s
cd ~/docker-study/k8s
Windows (PowerShell):
New-Item -ItemType Directory -Force "$HOME\docker-study\k8s"
cd "$HOME\docker-study\k8s"
VS Code 로 k8s 폴더를 열고 pod.yaml 을 만듭니다. 내아이디 를 본인 Docker Hub 아이디로 바꾸세요.
apiVersion: v1
kind: Pod
metadata:
name: guestbook
labels:
app: guestbook
spec:
containers:
- name: web
image: 내아이디/guestbook:v1
ports:
- containerPort: 8000
3-2. 적용
kubectl apply -f pod.yaml
kubectl get pods -o wide --show-labels
출력 예시:
NAME READY STATUS RESTARTS AGE IP NODE NOMINATED NODE READINESS GATES LABELS
guestbook 1/1 Running 0 8s 10.244.2.5 desktop-worker <none> <none> app=guestbook
LABELS에app=guestbook이 보입니다. 7주차부터 이 라벨이 중요해집니다.
3-3. 브라우저로 접속: port-forward
Pod 는 클러스터 안의 IP(10.244.x.x)를 가져서 노트북에서 바로 접속할 수 없습니다. 테스트용으로 노트북 포트를 Pod 에 연결합니다.
kubectl port-forward pod/guestbook 8080:8000
출력 예시: 이 터미널은 연결을 유지하는 동안 그대로 둡니다.
Forwarding from 127.0.0.1:8080 -> 8000
Forwarding from [::1]:8080 -> 8000
브라우저에서 http://localhost:8080 → 방명록 v1 이 보입니다.
응답한 서버(HOSTNAME) 가 Docker 때처럼 이상한 ID 가 아니라 guestbook(Pod 이름) 입니다. Kubernetes 는 Pod 이름을 호스트 이름으로 씁니다.
다 봤으면 port-forward 터미널에서 Ctrl + C 로 끊습니다.
실습 중 port-forward 를 켜 둔 채 다른 명령을 치려면 터미널을 하나 더 여세요.
3-4. Pod 안 들여다보기
kubectl exec guestbook -- hostname
kubectl exec guestbook -- env
kubectl logs guestbook
출력 예시 (env 일부):
APP_VERSION=v1
APP_COLOR=royalblue
KUBERNETES_SERVICE_HOST=10.96.0.1
...
--뒤가 Pod 안에서 실행할 명령입니다.KUBERNETES_SERVICE_HOST처럼 Kubernetes 가 자동으로 넣어 준 환경 변수도 보입니다.- 안에 들어가려면
kubectl exec -it guestbook -- sh(나올 때exit)
3-5. 같은 파일을 다시 apply 하면?
kubectl apply -f pod.yaml
출력: pod/guestbook unchanged
선언형이라서 "이미 원하는 상태" 면 아무것도 하지 않습니다.
kubectl run을 두 번 하면 "이미 있다" 는 에러가 나는 것과 비교해 보세요.
실습 4. Pod 를 지우면?
kubectl delete -f pod.yaml
kubectl get pods
출력:
pod "guestbook" deleted from default namespace
No resources found in default namespace.
Pod 를 직접 만들면 지워지거나 노드가 죽었을 때 그대로 사라집니다. "항상 N개 유지" 를 책임지는 것은 Deployment 입니다 → 7주차.
실습 5. 고장 난 Pod 진단하기
5-1. 이미지 이름 오타: ImagePullBackOff
일부러 guestbook 을 guestbok 으로 틀리게 씁니다.
kubectl run study-typo --image=내아이디/guestbok:v1
20초쯤 기다린 뒤:
kubectl get pod study-typo
출력 예시:
NAME READY STATUS RESTARTS AGE
study-typo 0/1 ImagePullBackOff 0 20s
원인을 찾아봅니다.
kubectl describe pod study-typo
출력 예시 (Events 일부):
Warning Failed 7s (x2 over 20s) kubelet ... Failed to pull image "내아이디/guestbok:v1": failed to pull and unpack image "docker.io/내아이디/guestbok:v1": failed to resolve reference "docker.io/내아이디/guestbok:v1": pull access denied, repository does not exist or may require authorization: server message: insufficient_scope: authorization failed
Warning Failed 7s (x2 over 20s) kubelet ... Error: ErrImagePull
Normal BackOff 19s kubelet ... Back-off pulling image "내아이디/guestbok:v1"
repository does not exist→ 저장소 이름이 틀렸거나, 비공개 저장소입니다.ErrImagePull(받기 실패) →ImagePullBackOff(잠시 쉬었다가 다시 시도하는 중). 쉬는 시간은 점점 늘어납니다.- 이미지 문제는
logs에는 아무것도 없습니다. 컨테이너가 시작조차 못 했기 때문입니다.describe의 Events 를 보세요.
kubectl delete pod study-typo
5-2. 앱이 계속 죽음: CrashLoopBackOff
시작하자마자 에러로 끝나는 컨테이너를 만듭니다.
kubectl run study-crash --image=alpine:3.24 -- sh -c "echo 'something wrong'; exit 1"
40초쯤 기다린 뒤:
kubectl get pod study-crash
출력 예시: RESTARTS 가 계속 올라가고, STATUS 가 Error 와 CrashLoopBackOff 를 번갈아 보입니다.
NAME READY STATUS RESTARTS AGE
study-crash 0/1 CrashLoopBackOff 3 (27s ago) 42s
이번에는 로그에 원인이 있습니다.
kubectl logs study-crash
출력: something wrong
kubectl describe pod study-crash
출력 예시 (일부):
Last State: Terminated
Reason: Error
Exit Code: 1
| ImagePullBackOff | CrashLoopBackOff | |
|---|---|---|
| 무슨 상황? | 이미지를 받지 못함 | 이미지는 받았는데 앱이 실행 후 죽음 |
| 어디를 보나? | describe 의 Events |
logs + describe 의 Exit Code |
| 흔한 원인 | 이름·태그 오타, 비공개 저장소 | 설정 누락(환경 변수, DB 주소), 코드 에러 |
--restart 를 주지 않아도 Pod 는 기본으로 계속 재시작을 시도합니다(restartPolicy: Always).
kubectl delete pod study-crash
실습 6. Namespace
kubectl create namespace study
kubectl apply -f pod.yaml -n study
kubectl get pods
kubectl get pods -n study
출력 예시:
No resources found in default namespace.
NAME READY STATUS RESTARTS AGE
guestbook 1/1 Running 0 7s
-n study를 안 주면default를 봅니다. 그래서 첫 번째 명령에는 아무것도 없습니다.
모든 Namespace 를 한 번에 보려면 -A 를 씁니다.
kubectl get pods -A
Namespace 를 지우면 그 안의 모든 것이 함께 지워집니다.
kubectl delete namespace study
kube-system 은 절대 지우거나 건드리지 마세요클러스터가 고장 납니다. 망가졌다면 Docker Desktop Kubernetes 설정 → Reset cluster 로 초기화할 수 있습니다.
실습 7. 정리
kubectl get pods -A | grep study
Windows PowerShell 은
kubectl get pods -A | Select-String study
아무것도 안 나오면 끝입니다. 클러스터는 지우지 마세요. 7주차에 계속 씁니다.
Docker Desktop Kubernetes 화면에서 Stop 으로 클러스터를 잠시 꺼 둘 수 있습니다. 다음 실습 전에 다시 켜면 됩니다.
Docker Hub 에 이미지를 못 올렸다면
Docker Desktop 의 Kubernetes 는 내 노트북에 있는 이미지도 쓸 수 있습니다(실제로 확인함). 4주차 실습 1~4 로 guestbook:v1, guestbook:v2 를 빌드해 두었다면 pod.yaml 의 이미지를 이렇게 바꾸세요.
image: guestbook:v1
다만 이 방법은 내 노트북에서만 통합니다. 실제 서버 클러스터는 레지스트리(Docker Hub 등)에서 받아야 하므로, 시간이 날 때 4주차 실습 5~6 을 꼭 해 두세요.
자주 나는 문제와 해결
| 증상 | 원인 | 해결 |
|---|---|---|
The connection to the server ... was refused / Unable to connect to the server |
클러스터가 꺼져 있거나 kubectl 이 다른 클러스터를 봄 | Docker Desktop 에서 Kubernetes running 확인, kubectl config use-context docker-desktop |
version difference between client ... and server ... exceeds the supported minor version skew |
오래된 kubectl 이 먼저 실행됨 | 실습 0-2 의 경고 상자 참고 |
| 클러스터 생성이 오래 걸리거나 실패 | 메모리 부족 | 다른 프로그램 종료, 노드 수를 2 또는 1 로 줄여서 다시 생성 |
ImagePullBackOff |
이미지 이름·태그 오타, Docker Hub 에 안 올림, 비공개 저장소 | describe Events 확인, Docker Hub 웹에서 이름 확인 |
CrashLoopBackOff |
앱이 시작 후 죽음 | kubectl logs 이름 (이전 실행 로그는 --previous) |
port-forward 후 bind: address already in use / unable to listen on any of the requested ports |
8080 을 다른 것이 사용 중 (5주차 Compose 등) | docker compose down 하거나 8081:8000 처럼 다른 포트 사용 |
Error from server (AlreadyExists) |
같은 이름이 이미 있음 (kubectl run 두 번 등) |
kubectl delete pod 이름 후 다시 |
YAML apply 시 error converting YAML to JSON |
들여쓰기·탭 문제 | 5주차 YAML 주의사항 참고 |
오늘 쓴 명령어 정리
| 명령어 | 하는 일 |
|---|---|
kubectl config current-context / use-context 이름 |
지금 보는 클러스터 확인 / 바꾸기 |
kubectl version |
클라이언트·서버 버전 |
kubectl get nodes [-o wide] |
노드 목록 |
kubectl get pods [-o wide] [--show-labels] [-n 이름 / -A] [-w] |
Pod 목록 |
kubectl run 이름 --image=이미지 [-- 명령] |
Pod 하나 바로 만들기 (명령형) |
kubectl apply -f 파일.yaml [-n 이름] |
파일대로 만들기·바꾸기 (선언형) |
kubectl describe pod 이름 |
상세 + Events |
kubectl logs 이름 [--previous] |
로그 |
kubectl exec [-it] 이름 -- 명령 |
Pod 안에서 명령 실행 |
kubectl port-forward pod/이름 8080:8000 |
노트북 포트 → Pod 포트 (테스트용) |
kubectl delete pod 이름 / delete -f 파일 |
삭제 |
kubectl create namespace 이름 / delete namespace 이름 |
Namespace 만들기 / 지우기 |
kubectl explain pod.spec.containers |
YAML 필드 설명 |
복습 과제
확인 퀴즈
- Control Plane 의 구성 요소 4가지와 각각의 역할은?
- Worker Node 에서 실제로 컨테이너를 실행하는 구성 요소는? 1주차에 본 것과 어떤 관계인가요?
- Pod 를
kubectl delete로 지우면 다시 생기나요? 왜 그런가요? ImagePullBackOff와CrashLoopBackOff는 각각 어떤 상황이고, 원인은 어디서 확인하나요?kubectl apply -f pod.yaml을 두 번 하면 어떻게 되나요? 이것을 무엇이라고 부르나요?- 방명록 화면의 HOSTNAME 이 Docker 때와 다르게
guestbook으로 나온 이유는?
- kube-apiserver(모든 요청의 창구), etcd(클러스터 상태 저장소), kube-scheduler(Pod 를 둘 노드 결정), kube-controller-manager(원하는 상태와 현재 상태를 맞추는 조정 루프)
- kubelet 이 지시하고 containerd(컨테이너 런타임)가 실제로 실행합니다. 1주차에 Docker 내부에서 본 containerd + runc 와 같은 것입니다.
- 다시 생기지 않습니다. Pod 를 직접 만들면 "N개 유지" 를 책임지는 컨트롤러가 없기 때문입니다. 그 역할은 Deployment(7주차)가 합니다.
ImagePullBackOff는 이미지를 받지 못한 상황으로describe의 Events 에서 원인을 봅니다.CrashLoopBackOff는 앱이 실행 후 계속 죽는 상황으로logs에서 원인을 봅니다.- 두 번째는
unchanged가 나오고 아무 일도 하지 않습니다. 원하는 상태를 적어 두면 그 상태로 맞춰 주는 선언형 방식이기 때문입니다. - Kubernetes 는 Pod 이름을 컨테이너의 호스트 이름으로 쓰기 때문입니다.
도전 과제 (선택)
kubectl run study-gen --image=nginx:1.30-alpine --dry-run=client -o yaml을 실행해 보세요. Pod 를 만들지 않고 YAML 만 출력합니다. YAML 을 처음부터 쓰기 어려울 때 쓰는 요령입니다.kubectl get pod guestbook -o yaml로 실행 중인 Pod 의 전체 YAML 을 보고, 내가 쓰지 않은status:부분에서podIP와phase를 찾아보세요.- Docker Desktop 대시보드의 Kubernetes 화면에서 Namespace 를 바꿔 가며 Pod 목록을 보세요. 터미널로 본 것과 같은 정보가 나옵니다.
오늘 Pod 는 지우면 그대로 사라졌습니다. 다음 주에는 "방명록 Pod 를 항상 3개 유지해" 라고 선언하는 Deployment 를 만들고, Pod 를 지워도 스스로 되살아나는 것, 그리고 v1 → v2 무중단 업데이트와 되돌리기(롤백) 를 해 봅니다.
네비게이션
| 이전 | 목록 | 다음 |
|---|---|---|
| ◀ 6주차 강의 노트 | 목록으로 | 7주차 강의 노트 ▶ |